Add detailed documentation #45
Conversation
|
|
||
| pprint.pprint(r.json()) | ||
| # => {'status': 'CLOSED'} | ||
| ``` |
There was a problem hiding this comment.
I can contribute with a curl guide if you want..I usually use curl to test such services
| <td>string</td> | ||
| <td>Must be <code>CANCELED</code>.</td> | ||
| </tr> | ||
| </table> |
There was a problem hiding this comment.
Is this guide generated automatically? Maybe we can copy the Flink documentation approach (that generates this automatically) or we can add something like swagger one day
| | EXPLAIN PLAN FOR ... | Show string-based explanation about AST and execution plan of the given statement | | ||
| | SELECT ... | Submit a Flink `SELECT` SQL job | | ||
| | INSERT INTO ... | Submit a Flink `INSERT INTO` SQL job | | ||
| | INSERT OVERWRITE ... | Submit a Flink `INSERT OVERWRITE` SQL job | |
There was a problem hiding this comment.
I would mention that SHOW CURRENT CATALOG/DATABASE are available but marked as experimental/evolving for the moment
| @@ -0,0 +1,8 @@ | |||
| # Flink SQL Gateway Documents | |||
|
|
|||
| Welcome to the documentation page of Flink SQL gateway. We currently have the following documents available. | |||
There was a problem hiding this comment.
move them to top level README.md
| ''' | ||
| ``` | ||
|
|
||
| The result of a `INSERT` statement will be returned once the insertion finished (be aware that if you're inserting a never-ending stream, this API call will block forever unless the job is canceled). |
There was a problem hiding this comment.
this API call will always get empty result
|
|
||
| pprint.pprint(r.json()) | ||
| ''' => | ||
| {'next_result_uri': '/v1/sessions/8797639f35e1ed71b734c035e03e98da/jobs/b1719d4ea8f6d41a830d44918cd7e4d0/result/1', |
There was a problem hiding this comment.
session id should be 918e6d1eff0c14228069edec25144022 (result of first example result)
| </tr> | ||
| <tr> | ||
| <th>Row Count</th> | ||
| <td colspan="3">≥1</td> |
There was a problem hiding this comment.
catalogs will always be non empty, but tables and views can indeed be empty
| <tr> | ||
| <td>change_flags</td> | ||
| <td>array of boolean</td> | ||
| <td><p>This field only appears for a streaming job result.</p><ul><li>If the i-th element is `true`, the i-th result row should be appended to the results of the job.</li><li>If the i-th element is `false`, the i-th result row should be retracted from the results of the job.</li></ul></td> |
There was a problem hiding this comment.
This field only appears for a streaming select job result.
There was a problem hiding this comment.
mark this as PublicEvolving, because flink-1.11 has updated this to RowKind
| <tr> | ||
| <td>schema</td> | ||
| <td>varchar</td> | ||
| <td>A serialized JSON string of the schema of the specified table. See gateway's <a href="https://github.com/ververica/flink-sql-gateway/blob/master/src/main/java/com/ververica/flink/table/gateway/rest/result/TableSchemaUtil.java"><code>TableSchemaUtil</code></a> for detailed format.</td> |
There was a problem hiding this comment.
mark this as PublicEvolving, the result need to be discussed
| </tr> | ||
| </table> | ||
|
|
||
| #### RESET |
|
Just another note: in the list of supported commands, I'll make a clear separation between commands that ends in a job execution and those that does not involve any interaction with the Flink cluster. I'd like to have this more clear when I started approaching to this project |
|
We created a quick openapi 3.0.0 spec to speak to the rest interface for our use case. It would be better if that spec was part of the repo. And even better if it was served from the gateway. If it is of interest, we can create a pull request and upload it. |
That's great! |
This PR adds detailed documentation for the gateway, including the REST API documentation and an API usage example.